Amplia os períodos analíticos e pagina os rankings na versão 2.7.1 - #161

O que esse PR faz?

Fecha a versão 2.7.1 com melhorias nas consultas analíticas da API:

• Permite recortes diários até hoje e consultas ao mês corrente. Uma data final em YYYY-MM no mês atual é limitada a hoje; dias explicitamente futuros são rejeitados.
• Mantém país/idioma em anos completos, permitindo consultar o ano corrente com totais disponíveis e cobertura provisória informativa.
• Intersecta os dias confirmados com o período solicitado, distingue dias futuros de dias ausentes e preserva a soma por campos mensais quando o mês inteiro está confirmado. Períodos sem dias confirmados não viram sucesso com contagem zero.
• Pagina os grupos dos rankings com cursor assinado: padrão de 5 e máximo de 20 grupos por página; limit continua sendo o número de itens por grupo, com padrão 100 e máximo 1000. O produto group_limit × limit não pode exceder 10000.
• Seleciona os grupos antes de agregar seus itens, esgotando as páginas de itens antes de calcular o topN. A seleção por país/idioma usa tuplas exatas, sem combinar indevidamente as dimensões.
• Amplia as distribuições para até 10000 grupos, com erro explícito acima desse limite, sem truncamento silencioso.
• Inclui meses parciais na descoberta analítica e preserva cobertura, avisos e paginação em CSV/XLSX, inclusive em páginas vazias. No XLSX, a cobertura mensal fica em uma aba separada para não ultrapassar o limite de caracteres por célula.
• Atualiza VERSION de 2.7.0 para 2.7.1 em um commit final separado.

Os relatórios oficiais COUNTER continuam restritos a meses completos e anteriores ao mês atual. Este PR não muda ingestão, granularidade dos índices, controles de acesso ou cotas da versão 2.7.0.

Onde a revisão poderia começar?

1. counter_api/dates.py e counter_api/extensions/dates.py: leitura comum das datas e políticas independentes para relatórios oficiais e consultas analíticas.
2. counter_api/extensions/coverage.py e counter_api/painless.py: recortes diários, cobertura e caminho de soma mensal.
3. counter_api/extensions/ranking.py e counter_api/extensions/pagination.py: seleção dos grupos, topN exato e vínculo do cursor ao período e aos filtros.
4. counter_api/extensions/exports.py: metadados e integridade do XLSX.
5. counter_api/extensions/views.py, counter_api/extensions/openapi.py e README.md: contrato público e exemplos.

Como este poderia ser testado manualmente?

Em ambiente com dados e cobertura disponíveis, respeitando o modo de acesso e as cotas configuradas:

1. Consulte /r51/extensions/capabilities?platform=scl: confira other_granularity=day, país/idioma em year e disponibilidade de meses parciais confirmados.
2. Consulte /r51/extensions/ranking para entity_type=journals, parent_type=collection, parent_id=scl, platform=scl, usando um intervalo diário com dados. Confira as contagens e os dias incluídos em coverage. Repita com o mês corrente em YYYY-MM e confirme a data final limitada a hoje.
3. Para o ranking anual, use entity_type=articles, parent_type=journal, um parent_id válido e group_by=country,language, de janeiro a dezembro do mesmo ano, inclusive o corrente. Use group_limit=1 e limit=10; siga pagination.next_cursor com o mesmo período e filtros. Confira a continuidade dos grupos e a ordenação dos itens por contagem, com desempate estável por chave.
4. Reutilize o cursor com outro período ou filtro: deve retornar 400. Também verifique group_limit=21 e group_limit=20&limit=501. Limites válidos e formato de saída podem mudar entre páginas.
5. Baixe páginas em CSV e XLSX: confira os metadados de paginação e cobertura. No XLSX, confira Coverage e Coverage months; em uma página sem cobertura, a paginação fica na aba Pagination.
6. Consulte /r51/extensions/distribution com entidade e dimensões válidas: confira total, ausência de truncamento e erro explícito ao exceder o teto de grupos.
7. Confirme que datas futuras explícitas são rejeitadas e que os relatórios oficiais continuam rejeitando o mês corrente e recortes que não cubram meses inteiros. Nas extensões, coverage_policy=strict mantém a exigência de meses completos confirmados.

Algum cenário de contexto que queira dar?

As extensões analíticas não precisam herdar a restrição temporal dos relatórios oficiais. Os recortes recentes usam as métricas já existentes, sem reprocessamento nem nova granularidade de armazenamento.

Screenshots

N/A

Quais são os tickets relevantes?

N/A

Referências

N/A

Segurança da informação (NSI.04)

Este PR manipula dados sensíveis ou pessoais (LGPD)?

• Sim
• Não — trabalha com as métricas agregadas já expostas pela API; não adiciona campos pessoais.

Este PR altera autenticação, autorização, controle de acesso ou gerenciamento de sessão?

• Sim
• Não — mantém os modos de acesso e as cotas existentes. O novo cursor é assinado e vinculado à consulta para proteger a integridade da paginação; não concede acesso.

Este PR introduz, atualiza ou remove dependências de terceiros?

• Sim
• Não

Este PR foi validado pelo pipeline de segurança (SonarQube / Trivy)?

• Sim — link do job:
• Não aplicável a este PR

Pendente de execução/verificação no GitHub; não se declara aprovação de SonarQube/Trivy com base nas verificações locais. Gitleaks local e hooks de commit aprovados.

Este PR concatena, monta ou executa comandos SQL, HTML ou JavaScript a partir de entrada externa?

• Sim
• Não — o script Painless tem fonte estática e recebe os recortes por parâmetros; filtros são enviados como estruturas de consulta ao OpenSearch.

Este PR expõe novos endpoints, telas ou serviços?

• Sim
• Não — amplia parâmetros e respostas das rotas analíticas existentes, mantendo seus controles de acesso.

Algum segredo, senha, chave ou token está sendo adicionado ao código-fonte?

• Não, nenhum segredo foi commitado
• Sim (bloquear merge e corrigir antes de prosseguir)